</> A WALKTHROUGH
Skillful
Alhazen
Designing an ontology-backed notebook for agentic curation -- decisions, tradeoffs, and what I learned.
Brief
"The duty of the man who investigates the writings of scientists, if learning the truth is his goal, is to make himself an enemy of all that he reads, and, applying his mind to the core and margins of its content, attack it from every side."
-- Ibn al-Haytham, 965-1039 AD
The starting point
The agent was smart.
Its memory was post-it notes.
We anthropomorphize "memory" in agent work. But scientists don't remember everything -- they use notebooks. They write things down with structure so they can find it later and subject it to scrutiny.
Bioinformatics taught us data hygiene 20 years ago. We built ontologies for exactly this reason. The same problem is back.
Conceptual diagram: post-it notes scattered on a wall vs. a structured lab notebook with typed entries
Solomon Hynes -- AI Engineering World's Fair, 2025
The intellectual motivation
Every agent makes ontological commitments.
Most are invisible.
LLMs are so good at semantics that we stop noticing the modeling decisions buried in prompts and markdown.
What's a "contact"? What's a "finding"? What's the relationship between a person and a role?
This framework makes those commitments explicit and evolvable.
Conceptual diagram: implicit commitments (buried in conversation threads and MD files) vs. explicit commitments (typed schema with clear entity/relation definitions)
Decision one
Structured memory,
not Markdown sprawl.
What most agent stacks do
Save context to MD files or a RAG index. Fine for chat. Falls apart when you need to ask structured questions.
What I chose
TypeDB: typed entities, typed relations, persistent across sessions, queryable across domains. Harder to set up. Worth it.
Diagram: flat files and RAG blobs on the left; a knowledge graph with typed nodes and labeled edges on the right
Decision two
Domain becomes a plug-in,
not a rewrite.
Anatomy of a skill
skills/jobhunt/ SKILL.md // agent instructions schema.tql // typed schema namespace jobhunt.py // CLI commands dashboard/ // optional UI
One agent, many domains. Same notebook, same deploy. Onboarding a new skill is one PR.
Diagram: a skill directory contributing four things (schema, CLI, instructions, dashboard) into the shared notebook
Decision three -- the hardest
"I can't represent this"
is the most important signal.
Most agent stacks silently skip what they can't store. I treat schema rejection as a trigger for evolution.
The loop
Circular diagram: agent tries -- schema rejects -- gap filed -- schema evolves -- agent succeeds
Decision four
Use the runtime you
already pay for.
Claude Code IS the agent runtime. Skills mount via .claude/skills/. I don't ship my own orchestrator.
Tradeoff
Less control over the agent loop.
Win
~10x less code. Deploy is git clone && make build.
Diagram: custom orchestrator (crossed out, complex) vs. Claude Code + skills (simple, three boxes)
An example
Person vs. Role --
explicit ontology pays off.
LLM instinct
Author sub Person
Alice can't be an author, reviewer, and patient at once. Single inheritance breaks.
BFO / UFO pattern
Alice bears Author
Person is rigid. Role is anti-rigid. Roles come and go. Person stays clean.
This clarity only comes from making commitments explicit. LLM linguistic logic quietly bakes in errors you find at scale.
Diagram: Alice with multiple roles attached via role-bearing relations (clean) vs. Author-sub-Person single-inheritance tree (broken)
What's deployed
Same notebook,
different domains.
Screenshot: dashboard view -- jobhunt dossier or tech-recon investigation
Outcomes
Results, and three honest open problems.
What worked
CAIS 2026 -- paper accepted at ACM Conference on Agents and Agent Systems
6 working skills across biomedicine, careers, and technical investigation
One codebase -- deploy is git clone && make build
What's still hard
Schema migration -- attribute changes still mean re-ingestion
Concurrent gap PRs -- two fixes can conflict
Proposed vs. committed -- no intermediate schema state yet
None of these are blocking. They're the next phase of work -- and they're the kind of problems that only emerge once the core architecture is working.
Any questions?
Gully Burns -- github.com/GullyBurns/skillful-alhazen